home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / compression / filepackers / stonecracker.lha / StoneCracker / docs / stc.doc < prev    next >
Encoding:
Text File  |  1994-01-05  |  29.0 KB  |  820 lines

  1. =-=-=-=-=-=-=-=-=-=-=-=> StoneCracker v4.10.3 <=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  2.  
  3. This new version is major bugfix. No big changes or improvments have done.
  4.  
  5.     · Fixed some bugs:
  6.       - When trying to save decrunched (lib)executable to a writeprotected
  7.         disk, Stc won't crash anymore
  8.       - Added '** StoneCracker: User aborted.. ' message, when user aborts
  9.         single file crunching in commandline
  10.       - If iconify fails Stc won't crash
  11.       - Stc verified file overwriting only once with the same file. Now
  12.         checked every time.
  13.  
  14.     · PAL/NTSC check - now larger filerequesters are possible under PAL
  15.     · Dest dir (when presented) is also used with single file saving (huuray,
  16.       I forgor to add this to previous version.. :(
  17.       (Note that load/save requesters use the same filerequester)
  18.     · Some slight modification to code.. Not visible to a user
  19.     · New stc.library & stc020.library versions 3.304 have faster decrunchers
  20.       and slightly faster crunching (4-5%)!
  21.     · Stc shows the library version it's using.
  22.  
  23.   --> INCLUDED AUTODOCS & INCLUDE FILES FOR PROGRAMMERS!!!!
  24.  
  25.     · Explained (professional) kill system decruncher a bit better. A4
  26.       register contains info about CPU type. See 2.2.2.3!
  27.  
  28.  
  29.     · Program sizes are now:
  30.  
  31.         stc             31984 bytes
  32.         stc.library     5960  bytes
  33.         stc020.library  5908  bytes
  34.  
  35.  
  36.  
  37.  
  38. =-=-=-=-=-=-=-=-=-=-=-=> StoneCracker v4.10.2 <=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  39.  
  40.                                 Contents
  41.  
  42.  
  43.  
  44. 1 General info
  45. 1.1 Disclaimer
  46. 1.2 Copyright & Distribution
  47. 1.3 Introduction to StoneCracker
  48. 1.4 Requirements
  49. 1.5 Contents of the package
  50. 1.6 The future
  51.  
  52. 2 GUI Settings
  53. 2.1 Filetypes
  54.     2.1.1 Executable programs
  55.     2.1.2 Data files
  56.     2.1.3 Absolute programs
  57. 2.2 Decrunchers
  58.     2.2.1 E-Decrunchers for Executables
  59.           2.2.1.1 Build In
  60.           2.2.1.2 Library
  61.     2.2.2 A-Decrunchers for Absolutes
  62.           2.2.2.1 Normal
  63.           2.2.2.2 Plain
  64.           2.2.2.3 Professional
  65.     2.2.3 Absolute decruncher defs
  66.           2.2.3.1 Load address
  67.           2.2.3.2 Jump address
  68.           2.2.3.3 Decr address - decruncher address
  69.           2.2.3.4 USP address - user stackpointer address
  70.           2.2.3.5 SSP address - system stackpointer address
  71.           2.2.3.6 SR - status register
  72. 2.3 Packmode
  73. 2.4 Seclen - security length
  74. 2.5 DataID
  75. 2.6 Dest dir - destination directory
  76. 2.7 Save prefs - save preferences
  77.  
  78. 3 Using GUI
  79. 3.1 Information gadgets
  80.     3.1.1 File name
  81.     3.1.2 File length
  82.     3.1.3 Processed length
  83.     3.1.4 Crunched length
  84. 3.2 Output window
  85. 3.3 Load file
  86. 3.4 Save file
  87. 3.5 Delete file
  88. 3.6 Iconify
  89. 3.7 Quit
  90. 3.8 Shortcuts
  91.  
  92. 4 Using commandline
  93. 4.1 What I can do from commandline?
  94. 4.2 List of options
  95.     4.2.1 Filetypes -fe, -fel, -fa, -fap, -fak
  96.     4.2.2 Packmode -p0, -p1, -p2, -p3, -p4
  97.     4.2.3 Absolute decruncher defs
  98.           4.2.3.1 Load address -L
  99.           4.2.3.2 Jump address -J
  100.           4.2.3.3 Decr address - decruncher address -D
  101.           4.2.3.4 USP address - user stackpointer address -U
  102.           4.2.3.5 SSP address - system stackpointer address -S
  103.           4.2.3.6 SR - status register -R
  104.     4.2.4 Other options
  105.           4.2.4.1 Overwriting file -o0, -o1
  106.           4.2.4.2 DataID -i
  107.           4.2.4.3 Online info -d, ?
  108. 4.3 Multifile crunching
  109.  
  110. 5 Advanced info
  111. 5.1 Tips for using StoneCracker
  112. 5.2 Decrunch info header & decrunching
  113. 5.3 Hunk preprocessor
  114. 5.4 Includes & autodocs for stc.library
  115.  
  116.  
  117.              Don't get confused b'cos of my bad Engleesh!!
  118.     
  119.  
  120. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  121.                                 Document
  122.  
  123.  
  124.  
  125. 1 General info
  126.  
  127. 1.1     Disclaimer
  128.  
  129.         The author cannot be held liable for the suitability or accuracy
  130.         of this manual  and/or the program(s) it describes. Any damage
  131.         directly or indirectly caused by the use or misuse of this manual
  132.         and/or the program it describes is the sole responsibility of the
  133.         user her/him self.
  134.  
  135.  
  136.  
  137. 1.2     Copyright & Distribution
  138.  
  139.         StoneCracker v4.10.2 professional - written in C
  140.         (c) 1991-93 Jouni 'Mr.Spiv' Korhonen of StoneWare SoftWorks
  141.  
  142.         Stc.library v3.303 - written entirely in assembly
  143.         (c) 1993 jouni 'Mr.Spiv' Korhonen of StoneWare SoftWorks
  144.                & Marcus 'Cozine' Ottosson (optimized decrunchers!)
  145.  
  146.                         Jouni Korhonen
  147.                         Hiihtomajantie
  148.                         11120 Riihimaki
  149.                         Finland
  150.  
  151.                         Email: jikorhon@cc.helsinki.fi
  152.  
  153.  
  154.         Reqtools.library  (c) Nico François
  155.  
  156.         GadToolsBox  (c) 1992-93 Jaba Development
  157.  
  158.         StoneCracker (just Stc for now on) (c) StoneWare SoftWorks. All
  159.         rights reserved. This program is Public Domain as long as you
  160.         don't make any money with it.
  161.  
  162.         If you are interested in using this program in your commercial
  163.         products just contact me (use Email for faster reply).
  164.  
  165.         If you like this cruncher very much send some money, so I could
  166.         purchase a real accelerator or A1200.. 8^}
  167.  
  168.  
  169.  
  170. 1.3     Introduction to StoneCracker
  171.  
  172.         What Stc actually is? Stc is an executable/data/absolute file
  173.         cruncher, not an archiver. Powerpacker, Imploder and the others
  174.         do the same job as Stc but not so efficiently. Stc was designed
  175.         to fulfil my own needs and includes those features I think useful.
  176.  
  177.         Algorithm used in Stc is called S404. Some LZ variant I think but
  178.         entirely developed by me and you can notice it (slow & bad
  179.         efficiency). The name is actually a verion number, where S means
  180.         StoneCracker and 404 means v4.04. S404 uses 66Kb for a look ahead
  181.         buffer and 24Kb for a hash table to speedup crunching.
  182.  
  183.         Although S404 can't compete with well written LZH, lh5, etc
  184.         algorithms it still does the best result when compared to other
  185.         single file crunchers (Powerpacker, Imploder, Spike, Crm, etc).
  186.         It's faster and more efficient. Next version S405 already exists!
  187.         And it crunches slightly better (1Kb better per 150Kb).
  188.  
  189.         There are two versions of stc.library: stc.library for 68000/010
  190.         CPUs and stc020.library for 68020++ CPUs. If your Amiga has 68020++
  191.         Stc tries first open stc020.library instead of stc.library. The
  192.         difference between these libraries are that stc020.library uses
  193.         new addressing modes and takes the advantage of odd addresses. No
  194.         significant speed increasement though but faster anyway.
  195.  
  196.         You can use Stc either from commandline or GUI.
  197.  
  198.         From commandline multifile crunching with asterix '*' is possible
  199.         and from GUI with multiselect thru filerequester.
  200.  
  201.         Stc detects all S403 & S404 crunched files automatically and can
  202.         decrunch them.
  203.  
  204.         Cache support with all decrunchers. VBR check with kill OS
  205.         decruncher.
  206.  
  207.         Fast decrunchers! Thanks Marcus!
  208.  
  209.         I used A2000c 000/28MHz (poor man's accelerator) + kick2.04 + 5Mb
  210.         ram + 140Mb HD. I had 3Mb but I ran out of memory when compiling
  211.         the main C program 8^}  (Køøl.. And the program size is just 31908
  212.         bytes..)
  213.  
  214.  
  215.  
  216. 1.4     Requirements
  217.  
  218.         Stc works ok on stock A500. 512Kb will do but atleast 1Mb and
  219.         fast memory are more comfortable. There's no separate NTSC mode.
  220.         The custom screen is always opened to fit into NTSC (sorry PAL
  221.         users).
  222.  
  223.         Tested in KickStarts 1.3, 2.04 and 3.0.
  224.  
  225.         If you are using KickStart 1.3 remeber to use 1.3 version of
  226.         reqtools.library and gadtools13.library.
  227.  
  228.  
  229.  
  230. 1.5     Contents of the package
  231.  
  232.         This package should include following files:
  233.  
  234.          · stc                      31908 bytes ; main program
  235.          · stc.info                             ; an icon
  236.  
  237.          · libs/stc.library          5936 bytes ; any kick
  238.          · libs/stc020.library       5888 bytes ; any kick, 68020++
  239.          · libs/reqtools.library                ; kick2.0++
  240.          · libs13/reqtools.library              ; kick1.3++
  241.          · libs13/gadtools13.library            ; kick1.3++
  242.  
  243.          · docs/stc.doc                         ; this file
  244.  
  245.          · sources/optidec.s                    ; optimised S404 decruncher
  246.          · sources/cache.s                      ; set caches properly
  247.  
  248.  
  249. 1.6     The future
  250.  
  251.         For crying out loud there is no future with Stc. I have dropped
  252.         this project b'cos it's quite frustrating to develope your own
  253.         algorithm without any knowledge of already existing and better
  254.         algorithms. Also I think I should study some tree techniques to
  255.         improve the speed.
  256.  
  257.         If I ever release a new version of Stc, it will surely be based
  258.         on some already existing algorithm. (I found some interesting
  259.         sources from several ftp sites ;^)
  260.  
  261.         Of course minor bugfixes are possible...
  262.  
  263.  
  264.  
  265. 2 GUI Settings
  266.  
  267. 2.1     Filetypes
  268.  
  269. 2.1.1   Executable programs
  270.  
  271.         Executable programs are normal program files that you can run
  272.         from CLI or WorkBench. When you load any file, Stc first does
  273.         a filetype check for that file. If hunk_header is found from
  274.         the file Stc goes on with loading and hunk processing.
  275.         If there aren't hunk_header, filetype is internally changed to
  276.         data and Stc goes on with loading and crunching.
  277.  
  278.         Hunk processing means that the standard hunk structure of the
  279.         file is converted to Stc's own shorter form. Note! If your
  280.         program includes any debug, symbol, name or external hunks they
  281.         are deleted.
  282.  
  283.         At the moment Stc's hunk processor can handle following hunk
  284.         types: hunk_header, hunk_code, hunk_data, hunk_bss, hunk_reloc32,
  285.         hunk_symbol, hunk_debug, hunk_external, hunk_name and hunk_end.
  286.         Other hunk types will cause an error.
  287.  
  288.         For more info about Stc's hunk processor read 5.3.
  289.  
  290. 2.1.2   Data files
  291.  
  292.         When filetype data is selected, Stc doesn't care about the
  293.         contents of the file. Also no decruncher is attached to the
  294.         crunched file. Standard fileheader is attached to the file.
  295.         For more info read 5.2.
  296.  
  297. 2.1.3   Absolute programs
  298.  
  299.         Absolute programs are sign of *really* *bad* programming habbit on
  300.         Amiga. You better know what you are doing! Loaded file is handled
  301.         as a data file and a decruncher is attached to the crunched file.
  302.         The decruncher makes it possible to execute your absolute program
  303.         and after loading decrunch it into certain memory location.
  304.         Stc supports caches & VBR with absolute decrunchers.
  305.  
  306.  
  307.  
  308. 2.2     Decrunchers
  309.  
  310. 2.2.1   E-Decrunchers for executables
  311.  
  312. 2.2.1.1 Build in decruncher attaches a decruncher and a relocator to the
  313.         crunched file. Then it's possible to run crunched program as it
  314.         wasn't crunched. After decrunching the relocator allocates all
  315.         needed memory blocks for the program and the moves & relocates
  316.         the program run there.
  317.  
  318.         Before running decrunched & relocated program, both instruction and
  319.         data caches are flushed and the memory for crunched data is
  320.         freed. Build in decruncher works with all kickstarts.
  321.  
  322. 2.2.1.2 Library decruncher does everything that build in decruncher does
  323.         but needs to find stc.library from your system (libs drawer). The
  324.         advantage of the library decruncher is that it's much shorter
  325.         (just the opening code for stc.library and one function call)
  326.         and b'cos the routines in the library are highly optimized,
  327.         whole decrunching & relocating process takes much less time.
  328.  
  329. 2.2.2   A-Decrunchers for absolutes
  330.  
  331. 2.2.2.1 Normal decruncher is quite simple. It just decrunches your program
  332.         into certain memory location and runs it. The decruncher needs
  333.         only load address (see 2.2.3.1) and jump address (see 2.2.3.2).
  334.  
  335.         After decrunching both instruction and data caches are flushed.
  336.         Note! Exec function ClearCacheU() is used for that. So if you have
  337.         taken over the OS... BanG may happen!
  338.  
  339. 2.2.2.2 Plain decruncher is actually not a decruncher b'cos you can't run
  340.         it from CLI or WorkBench. Plain decruncher doesn't include any
  341.         hunks stuff (not runable..) or cachecode. Otherwise it works just
  342.         like normal decruncher.
  343.  
  344. 2.2.2.3 Professional decruncher is useful when you need to take over the OS
  345.         or decrunch your (long) program into very low memory. Following
  346.         things are done before decrunching:
  347.                 - CPU to supervisor (Exec function SuperVisor() )
  348.                 - All interrupts off ($7fff to IntEna)
  349.                 - All DMAs off ($7fff to DmaCon)
  350.                 - All internal drives are turned off
  351.                 - If 68010++ exists VBR is set to 0
  352.                 - USP is relocated (see 2.2.3.4)
  353.                 - SSP is relocated (see 2.2.3.5)
  354.                 - Decruncher code is moved (see 2.2.3.3)
  355.                 - If 68020++ exists caches are flushed (no OS anymore)
  356.         And after decrunching:
  357.                 - If 68020++ exists caches are flushed (no OS anymore)
  358.                 - Status register is modified (see 2.2.3.6)
  359.  
  360.                 - NOTE! A4 register contains info about the CPU. If
  361.                   A4 = $ffffffff your CPU is 68020/030/040 and if
  362.                   A4 = $00000000 your CPU is 68000/010.
  363.  
  364.         If decrunched program would overwrite even parts of the crunched
  365.         data then cruncher data is move in memory so that decrunching is
  366.         possible without lockups.
  367.  
  368. 2.2.3   Absolute decruncher defs
  369.  
  370. 2.2.3.1 Load address (in hexadecimales) is the memory location you want
  371.         your program to be decrunched.
  372.  
  373. 2.2.3.2 Jump address (in hexadecimals) is the start (run here) address of
  374.         your program.
  375.  
  376. 2.2.3.3 Decruncher address (in hexadecimals) is the memory location you
  377.         want to place the decruncher code. Used only with professional
  378.         decruncher (see 2.2.2.3).
  379.  
  380.         Don't place inside your stack memory or program memory. The code
  381.         is 284 (=$11c) bytes long.
  382.  
  383. 2.2.3.4 USP = user stackpointer address (in hexadecimals) is the top
  384.         memory location for your user stack. Used only wirh professional
  385.         decruncher.
  386.  
  387. 2.2.3.5 SSP = system stackpointer address (in hexadecimals) is the top
  388.         memory location for your system stack. SSP is used by the pro
  389.         decruncher, interrupts, traps etc. whenever the supervisor bit is
  390.         set in the status register (see 2.2.3.6). Used only with
  391.         professional decruncher.
  392.  
  393. 2.2.3.6 SR = status register is loaded with this value after decrunching.
  394.         Used only with professional decruncher.
  395.  
  396.  
  397.  
  398. 2.3     Packmode
  399.  
  400.         There are five packmodes available. The number 16K, 8K, etc means
  401.         the maximum distance S404 crunchroutine tries to find equal
  402.         strings. The higher the packmode value is the better the crunch
  403.         result is. Though with small files lower packmode value may give
  404.         better result than the highest value (testing.. testing..).
  405.  
  406.         The packmode doesn't affect to memory usage during crunching or
  407.         decrunching but the lower the packmode is the faster the cruncher
  408.         is.
  409.  
  410.  
  411.  
  412. 2.4     Seclen - security length
  413.  
  414.         This value has quite important role. Better way to say security
  415.         length is overlap distance. If source (crunched) and destination
  416.         (uncrunched) data overlap, the destination must be atleast
  417.         'security length' bytes in higher memory than the source. It will
  418.         quarantee 100% safe decrunching.
  419.  
  420.         Also if crunching fails at the begining of the file, increasing
  421.         the security length may solve the problem.
  422.  
  423.  
  424.  
  425. 2.5     DataID
  426.  
  427.         DataID is a string that is automatically added into every crunched
  428.         data file. For example is dataID is 'argh' then '.argh' is added
  429.         into crunched data files. If there isn't dataID nothing is added.
  430.  
  431.  
  432.  
  433. 2.6     Dest dir - Destination directory
  434.  
  435.         Destination directory is only used when you select multiple files
  436.         from the filerequester. Crunched & decrunched files are
  437.         automatically saved to destination directory. Empty destination
  438.         directory is equal to the directory you selected the files.
  439.  
  440.  
  441.  
  442. 2.7     Save prefs - save preferences
  443.  
  444.         Save preferences save the currect state of GUI gadgets and dataID
  445.         string into S: (s drawer) as stc.cfg.
  446.  
  447.         Stc.cfg is automatically loaded when GUI is used.
  448.  
  449.  
  450.  
  451. 3 Using GUI
  452.  
  453.         GUI aka Graphical User Interface. The GUI was originally developed
  454.         with Gadtoolsbox and after slight modifications it also works with
  455.         kick1.3 (uses gadtools13.library then).
  456.  
  457.         Here's a short list of different gadgets and what you can do with
  458.         them.
  459.  
  460. 3.1     Information gadgets
  461.  
  462. 3.1.1   File name shows the name of the loaded file (in buffer). If this
  463.         text gadget is empty there's no file in buffer.
  464.  
  465. 3.1.2   File length is the size in bytes of the file in the buffer.
  466.  
  467. 3.1.3   Processed length shows the file length after precossing hunks.
  468.         For data and absolute files processed length is the same as the
  469.         file length.
  470.  
  471. 3.1.4   Crunched length
  472.  
  473.         File length after crunching. The length also includes 16 bytes of
  474.         decrunch info header (see 5.2). 
  475.  
  476.  
  477.  
  478. 3.2     Output window
  479.  
  480.         The output window (console) on the right side of the screen is
  481.         mostly used to output some system messages. Some error messages
  482.         include '(de:???)' where 'de' means 'dos error'.
  483.  
  484.  
  485.  
  486. 3.3     Load file
  487.  
  488.         When you press this gadget a filerequester shows up and you can
  489.         select one or more files to crunch or decrunch.
  490.  
  491.         If you selected multiple files they are automatically saved to
  492.         destination directory. Also decrunching multiple files is
  493.         possible.
  494.  
  495.  
  496.  
  497. 3.4     Save file
  498.  
  499.         When you press this gadget a (save)filerequester shows up and you
  500.         can select or write a save file name and path.
  501.  
  502.         Note that if you selected multiple files only the last crunched &
  503.         decrunched file remains in buffer. The other ones are saved
  504.         automatically to the destination directory (see 2.6).
  505.  
  506.  
  507.  
  508. 3.5     Delete file
  509.  
  510.         When you press this gadget a filerequester shows up and you can
  511.         select one or more files to delete.
  512.  
  513.  
  514.  
  515. 3.6     Iconify
  516.  
  517.         Iconify will free all buffers, close some libraries, close window
  518.         and screens and free used resources.
  519.  
  520.         A little window is opened and when you press right mousebutton
  521.         over it Stc will restart.
  522.  
  523.  
  524.  
  525. 3.7     Quit
  526.  
  527.         Exit this marvellous program.
  528.  
  529.  
  530.  
  531. 3.8     Shortcuts
  532.  
  533.         Almost every gadget can also be used thru keyboard. Shortcut keys
  534.         are marked with underscore.
  535.  
  536.  
  537.  
  538. 4 Using commandline
  539.  
  540. 4.1     What I can do from commandline?
  541.  
  542.         Stc can do everything from commandline that from GUI except for
  543.         decrunching. Actually you have more possibilities b'cos you
  544.         don't have to always select from predefined values.
  545.  
  546.         It's possible to crunch multiple files at one time. Multifile
  547.         crunching is a bit limited though. Read 4.3 for more info.
  548.  
  549.         You can abort crunching any time with CTRL-C!
  550.  
  551.         The structure of commandline is as follows:
  552.  
  553.         stc [-<options>] [sourcefile(s)] [destdir]
  554.          ^        ^       ^               ^
  555.          |        |       |               |
  556.          |        |       |               +-----> Destination directory is
  557.          |        |       |                       not needed if you want
  558.          |        |       +--> Files to load.     save crunched files into
  559.          |        |            Asterix '*' may    same directory you loaded
  560.          |        |            be used.           files from.
  561.          |        |
  562.          |        +--> These are case sensitive. None is compulsory.
  563.          |
  564.          +--> Program name
  565.  
  566.         Note! There can be only one sourcefile name at the time!
  567.         And if there's no destdir, sourcedir is used as a destdir.
  568.  
  569.  
  570.  
  571. 4.2     List of options
  572.  
  573.     Note! All options are case sensitive and may be placed
  574.         everywhere in commandline.
  575.  
  576. 4.2.1   Filetypes
  577.  
  578.         -fe  (default) sets filetype executable and decruncher will be
  579.              build in.
  580.         -fel sets filetype executable and decruncher will be library.
  581.         -fd  sets filetype data.
  582.         -fa  sets filetype absolute and decruncher will be normal. Only
  583.              load address (see 2.2.3.1 & 4.2.3) and jump address (see
  584.              2.2.3.2 & 4.2.3) are needed.
  585.         -fap sets filetype absolute and decruncher is plain. Only load
  586.              address (see 2.2.3.1 & 4.2.3) and jump address (see 2.2.3.2 &
  587.              4.2.3) are needed.
  588.         -fak sets filetype absolute and decruncher will be professional.
  589.              All absolute decruncher defs are needed (see 2.2.3 & 4.2.3).
  590.  
  591. 4.2.2   Packmode
  592.  
  593.         -p0  (default) sets packmode 16K (14 bits). (see 2.3)
  594.         -p1  sets packmode 8K (13 bits). (see 2.3)
  595.         -p2  sets packmode 4K (12 bits). (see 2.3)
  596.         -p3  sets packmode 2K (11 bits). (see 2.3)
  597.         -p4  sets packmode 1K (10 bits). (see 2.3)
  598.  
  599. 4.2.3   Absolute decruncher defs
  600.  
  601. 4.2.3.1 Load address
  602.  
  603.         With -L option you define the decrunch memory location for your
  604.         program. E.g -L3f002 will decrunch your program starting from
  605.         address $3f002. Given value is always haxadecimal. (see 2.2.3.1)
  606.  
  607. 4.2.3.2 Jump address
  608.  
  609.         With -J option you define the start address of your program that
  610.         the decruncher calls after decrunching. E.g -J40000 jump into
  611.         address $40000 after decrunching. (see 2.2.3.2)
  612.  
  613.         Note! If you don't define jump address, Stc assumes it's the same
  614.         as load address.
  615.  
  616. 4.2.3.3 Decr address - decruncher address
  617.  
  618.         This option affects only to the professinal decruncher!
  619.  
  620.         With -D option you define the location of the decruncher code.
  621.         E.g -D100 moves decruncher to address $100.
  622.         (see 2.2.3.3)
  623.  
  624.         Decruncher address defaults to $100.
  625.  
  626. 4.2.3.4 USP address - user stackpointer address
  627.  
  628.         This option affect only to the professional decruncher!
  629.  
  630.     With -U option you define the location of user stackpointer. E.g
  631.         -U20000 moves the top of USP to address $20000. The stack is
  632.         reloaded with defined value before decrunching. The decruncher
  633.         uses SSP - system stackpointer so it doesn't matter even if the
  634.         decruncher code is over the stack area.
  635.         (see 2.2.3.4)
  636.  
  637. 4.2.3.5 SSP address - system stackpointer address
  638.  
  639.         This option affect only to the professional decruncher!
  640.  
  641.     With -S option you define the location of system stackpointer.
  642.         E.g -S20000 moves the top of SSP to address $20000. The stack is
  643.         reloaded with defined value before decrunching. The decruncher
  644.         uses SSP during decrunching!
  645.     (see 2.2.3.5)
  646.  
  647. 4.2.3.6 SR - status register
  648.  
  649.         This option affect only to the professional decruncher!
  650.  
  651.         With -R option you define the state of status register. E.g
  652.         -R2010 forces CPU to supervisor mode and sets C flag.
  653.  
  654.         Note! Reloading is done just before jumping into your program!
  655.  
  656.  
  657.  
  658. 4.2.4   Other options
  659.  
  660. 4.2.4.1 Overwriting file
  661.  
  662.     With option -o1 (default) Stc always checks the destination
  663.         directory if there is a file with a same name as your file.
  664.         If there is you are asked whether to overwrite it or not.
  665.  
  666.         -o0 option overwrites without any warning. Very useful if
  667.         you are crunching multiple files.
  668.  
  669. 4.2.4.2 DataID
  670.  
  671.         With -i option you can define the dataID string that is added
  672.         to every crunched data file's name. Default string is 'stc'.
  673.         Maximum string length is seven chars.
  674.  
  675.         E.g -ijouni adds '.jouni' to crunched data files. If you want
  676.         to save data files without any ID string use -i alone.
  677.  
  678. 4.2.4.3 Online info
  679.  
  680.         There are two short help texts included into Stc. With ? you
  681.         get a quick reference of all commandline options and witd -d
  682.         option you get a list of internal defults and an example how
  683.         to use commandline.
  684.  
  685.  
  686.  
  687. 4.3     Multifile crunching
  688.  
  689.         You can crunch multiple files in one shot. It's quite limited
  690.         though. If the source filename includes asterix '*' Stc tries to
  691.         replace the asterix '*' with any string, character or nothing.
  692.         Note! There can be only one source filename at the time.
  693.  
  694.         The destination directory defaults to source directory. So you
  695.         don't have to define any destination directory. If you define a
  696.         destination directory Stc tries to find it and if the directory
  697.         isn't found Stc asks you to generate one.
  698.  
  699.  
  700.  
  701. 5 Advanced info
  702.  
  703. 5.1     Tips for using StoneCracker
  704.  
  705.         · If you press enter in GUI load address string gadget will be
  706.           activated.
  707.  
  708.         · Loaded file remains in buffer until you load a new one and start
  709.           loading it. (GUI)
  710.  
  711.         · 'Abort crunching' gadget cancels all files if you had selected
  712.           multiple files to crunch. (GUI)
  713.  
  714.  
  715.  
  716. 5.2     Decrunch info header & decrunching
  717.  
  718.         Every file crunched with Stc4.02a or Stc4.10.2 has following header
  719.         (16 bytes) at the beginning of the crunched data:
  720.  
  721.             "S404" or "S403"    ; cruncher version - string
  722.             Security length     ; overlap size - longword
  723.             Original length     ; decrunched length - longword
  724.             Crunched length     ; crunched length - longword
  725.                .                ; crunched data starts
  726.                .
  727.                .
  728.  
  729.         Security length is always 16 + something.
  730.  
  731.         There are also two control words at the end of crunched data. For
  732.         historical reasons it's quite wierd. I'll explain it with a 
  733.         following picture:
  734.  
  735.         <<- Lower memory                           Higher memory ->>
  736.  
  737.                   +------------ Crunched length ------------+
  738.                   |                                         |
  739.         InfoHeader|......................LastWord|BitCounter|MaxBits
  740.                             ^                 ^       ^         ^
  741.                             |                 |       |         |
  742.             Crunched data --+                 |       |         |
  743.                                               |       |         |
  744.                          Last crunched word --+       |         |
  745.                                                       |         |
  746.            How many used bits there are in LastWord --+         |
  747.                                                                 |
  748.                          Efficiency (packmode - only in S404) --+
  749.  
  750.         If both crunched data and destination memory overlap there must
  751.         be atleast 'Security length' distance between the start of the
  752.         crunched data and the start of the destination memory:
  753.  
  754.         <<- Lower memory                               Higher memory ->>
  755.  
  756.                   <<<-------------- Decrunching direction --------------
  757.  
  758.         InfoHeader|......................LastWord|BitCounter|MaxBits
  759.         ^
  760.         |             |<------------ Destination memory starts here ....
  761.         |             |
  762.         +-- SecLen ---+
  763.         |
  764.         +---------------> Crunched data starts here..
  765.  
  766.  
  767.  
  768. 5.3     Hunk preprocessor
  769.  
  770.         Every executable file is first preprocessed before crunching.
  771.         Processed files are always shorter than originals. Preprocessor
  772.         does the following for hunks:
  773.  
  774.           · All debug hunks generated by compiler are deleted (no way to
  775.             get them back!).
  776.           · There are no Hunk_ends
  777.           · Hunk header info at the beginning of the file is modified to
  778.             a shorter form:
  779.                   1 longword = (total number of hunks)-1 (=n)
  780.                 n+1 longwords = hunksizes & memory type (as normally)
  781.           · Hunk_code is converted to %01xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.L
  782.                                          +-------- datasize>>2 -------+
  783.           · Hunk_data is converted to %11xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.L
  784.                                          +-------- datasize>>2 -------+
  785.           · Hunk_bss is converted to %100000000000000000.W
  786.           · Hunk_reloc start with %000000000000000000.W and then
  787.             Repeat until (number of relocentries) = 0
  788.               1 word = number of relocentries (null if no relocs anymore)
  789.               1 word = relocate hunk number..
  790.               1 longword = %bbbbbbbbxxxxxxxxxxxxxxxxxxxxxxxx.L
  791.                             ^       +----- First reloc ----+
  792.                             |
  793.                             +--> Number of bytes to add to 'First reloc'
  794.                                    2       = 3 bytes per relocentry
  795.                                    4 or 6  = 2 bytes per relocentry
  796.                                    8 or 10 = 1 byte per relocentry
  797.                                    ?       = only one relocentry
  798.               followed by (number of relocentries) %bbbbbbbb reloc-
  799.               entries..
  800.           · End of processed hunks is %1111111111111111.W
  801.  
  802.  
  803.  
  804. 5.4     Includes & autodocs for stc.library
  805.  
  806.         There are proper include files for standard assemblers (atleast
  807.         DevPac and AsmOne understand them) and SAS/C.
  808.  
  809.         I haven't written any good autodocs. This document was already
  810.         enough. But if you are really interested in how to use
  811.         stc.library just post me and I'll send you the includes and
  812.         short autodocs.
  813.  
  814.         Btw.. include files for stc.library are a messish pile of shit!
  815.  
  816.  
  817.  
  818. MOVEQ #0,d0
  819. RTS                     ; succesful exit
  820.